@openpresentation/opf 0.26.3 → 0.26.5

package/README.md

@@ -99,12 +99,14 @@ The layout engine's names are not on the root. `composeSlide`, `fitText`, `layou
 
 ### Source editing: schema field queries, text addressing and syntax recovery
 
-Two browser-safe subpaths for source editors, the CLI and agents. `@openpresentation/opf/schema` reads the field model of a document from the JSON Schemas: `describeField(path, document?)` returns the types, description, enum values, default, examples, whether the parent requires it, the `oneOf` variants (and `primary`, the form a template should use), the ranked `children` of an object (required first, then the curated `COMMON_KEYS` order, then alphabetical; promoted regions, `extensions` and `$schema` are `advanced`), the item schema of an array (`itemInfo`) or map (`entryInfo`), `requiredChildren` and `freeText`, and `{ known: false }` for a path the schema does not describe; `catalogKindAt(path, document?)` names the catalog a reference field points into (`layouts`, `themes`, `colorSchemes`, `fontSchemes`, `narratives`, `audiences`, `purposes`, `tones`) from `schemaCatalogKinds` (also exported), core-side metadata keyed by schema name and JSON Pointer; the published schemas carry no vendor keyword and compile under strict Ajv, so a new reference field is one entry there and needs no editor change. The navigation helpers it is built on are exported too (`resolveSchema`, `schemaVariants`, `activeSchema`, `schemaAtPath`, `createSchemaValue`, `listSchemaFields`, `splitOpfPath`). `@openpresentation/opf/source` turns text into positions and back: `locate(text, "json", pointer, { part })` is the range of a JSON Pointer (`value`, `key`, `entry`, `open` or `colon`; the nearest ancestor with `exact: false` when the node is missing), `pathAt(text, "json", offset)` the path under a caret, and `analyzeJsonSyntax(text, { limit })` the root cause of each JSON syntax error, once, in position order (at most five), with a range, a message, a hint and the fixes that repair it (`Insert comma`, `Add { }`, `Remove "design"`, `Insert }`, `Use double quotes`, ...); `validate(text)` reports the same causes as `opf/json-syntax` findings. YAML and Markdown addressing is not there yet and returns `undefined`. See [validate](../../docs/validate.md).
+Two browser-safe subpaths for source editors, the CLI and agents. `@openpresentation/opf/schema` reads the field model of a document from the JSON Schemas: `describeField(path, document?)` returns the types, description, enum values, default, examples, whether the parent requires it, the `oneOf` variants (and `primary`, the form a template should use), the ranked `children` of an object (required first, then the curated `COMMON_KEYS` order, then alphabetical; promoted regions, `extensions` and `$schema` are `advanced`), the item schema of an array (`itemInfo`) or map (`entryInfo`), `requiredChildren` and `freeText`, and `{ known: false }` for a path the schema does not describe; `catalogKindAt(path, document?)` names the catalog a reference field points into (`layouts`, `themes`, `colorSchemes`, `fontSchemes`, `narratives`, `audiences`, `purposes`, `tones`) from `schemaCatalogKinds` (also exported), core-side metadata keyed by schema name and JSON Pointer; the published schemas carry no vendor keyword and compile under strict Ajv, so a new reference field is one entry there and needs no editor change. The navigation helpers it is built on are exported too (`resolveSchema`, `schemaVariants`, `activeSchema`, `schemaAtPath`, `createSchemaValue`, `listSchemaFields`, `splitOpfPath`). `@openpresentation/opf/source` turns text into positions and back: `locate(text, format, pointer, { part })` is the range of a JSON Pointer in JSON, YAML or Markdown (`value`, `key`, `entry`, `open` or `colon`; the nearest ancestor with `exact: false` when the node is missing; a Markdown slide field is located by the same ranges its findings use: the `layout=` token of an options comment, the text after `# ` or `- `), `pathAt(text, format, offset)` the path under a caret, `scanMarkdown(text)` the regions of a Markdown deck (front matter, slides, option comments, fences, notes) with the dialect's vocabulary (`SLIDE_OPTION_KEYS`, `BLOCK_OPTION_KEYS`, `FENCE_KINDS`, `METRIC_KEYS`), and `analyzeJsonSyntax(text, { limit })` the root cause of each JSON syntax error, once, in position order (at most five), with a range, a message, a hint and the fixes that repair it (`Insert comma`, `Add { }`, `Remove "design"`, `Insert }`, `Use double quotes`, ...); `validate(text)` reports the same causes as `opf/json-syntax` findings. See [validate](../../docs/validate.md).
 
 ### Validate (0.14.0)
 
 `validate(input, options?)` is the one checker, from the root and from `@openpresentation/opf/validator`. `input` is a parsed presentation or strict JSON text; the result is a `ValidationReport` whose `findings` (the shared `Finding` format, `spec/schemas/finding.schema.json`) each have a stable `opf/<rule>` id, a severity and one of six categories: `format` (JSON syntax, duplicate keys, schema), `references` (catalog references, assets, citations, datasets), `policy` (host `contracts`), `accessibility` (contrast, alt text, reading order, links), `layout` (overflow, type size, image resolution, fonts) and `content` (placeholders, empty slides, non-numeric chart cells). `valid` means no finding has severity `error`, which by default only `format`, `references` and `policy` findings can have. Text input adds line and column; `only`, `ignore` and `severity` pick and promote rules or categories; composition is lazy, so `validate(deck, { only: ["format"] })` costs what a schema check costs. Read-only and deterministic: no remote resources are fetched. See [the validate guide](../../docs/validate.md). A clean report does not certify layout, fonts, or native export fidelity.
 
+`describeFinding(finding, { document })` and `explain(ruleId)` put findings in plain words. `describeFinding` (from `@openpresentation/opf/source`) returns `{ message, next }` for any finding: what is wrong with the field in backticks, and what could come next ("did you mean `center`?"), written from the finding's own data and the document; every `opf/*` rule has its text. `explain` (also on the package root) returns a rule's summary, rationale, `fix` and a small before/after `example`. See [Plain-words text and `explain`](../../docs/validate.md#plain-words-text-and-explain).
+
 ### Patch, diff, merge and format (0.12.0)
 
 Added in 0.12.0 (not in 0.11.4 or earlier): `@openpresentation/opf/patch` is the one RFC 6902 implementation the CLI and the editor share (`applyPatch`, `applyPatchWithInverse`, `invertPatch`, strict pointer helpers, optional schema validation of the result); `@openpresentation/opf/diff` has `diff` (slide matching by id, content and similarity, moves, a readable report and a JSON Patch) and `merge` (three-way merge with conflict objects that never drop a side); `@openpresentation/opf/format` has `format` (canonical key order and layout, idempotent). See [the guide](../../docs/patch-diff-merge-format.md).

package/dist/browser.js

@@ -1,17 +1,20 @@
-import { OPFApiError } from './chunk-GLLR3AQ5.js';
-export { OPFApiError, OPFExportError, OPFImportError, OPFMoveToCustomError, copySlides, edit, embed, fill, fillRecords, localAssetSources, moveToCustom, parseSlideSelection, sameRecord, stats, updateFromCatalog } from './chunk-GLLR3AQ5.js';
+import { OPFApiError } from './chunk-UFEWQDQI.js';
+export { OPFApiError, OPFExportError, OPFImportError, OPFMoveToCustomError, copySlides, edit, embed, fill, fillRecords, localAssetSources, moveToCustom, parseSlideSelection, sameRecord, stats, updateFromCatalog } from './chunk-UFEWQDQI.js';
 export { specFileEntries, specFileKinds, specFilePaths } from './chunk-UJSAR6GF.js';
 export { FONT_POLICY, applyFontPolicyDecisions, fontAvailabilityDiagnostics, fontPolicyFor } from './chunk-PJSPHHRK.js';
 export { OPFDataImportError, ingest, parseTabularData } from './chunk-TKQ2VFV5.js';
-export { OPFPaginationError, paginate, paginateSlide } from './chunk-54OV2WQC.js';
-export { DECK_FORMATS, deckFormatOf, parse, stringify } from './chunk-FXNUM2PN.js';
-export { fromMarkdown, toMarkdown } from './chunk-WASENX2R.js';
-import './chunk-7RY7QWWJ.js';
-import './chunk-PB5X2VSV.js';
-export { OPFMarkdownError } from './chunk-DEI2M2H6.js';
-import './chunk-PXOXTJTN.js';
-export { diff, merge } from './chunk-YVNFACTC.js';
-export { CATALOG_SCHEMA, DEFAULT_VALIDATION_THRESHOLDS, OPFPatchError, OPFPatchValidationError, OPFValidationError, applyPatch, assertValid, assertValidCatalogRecord, catalogDisplayKinds, catalogSchemaNames, findValidationRule, resolveSlideContext, validate, validateCatalogRecord, validationCategories, validationRules } from './chunk-NJWI6MPT.js';
+export { OPFPaginationError, paginate, paginateSlide } from './chunk-EFMR32A5.js';
+export { DECK_FORMATS, deckFormatOf, parse, stringify } from './chunk-STIYINEL.js';
+export { fromMarkdown, toMarkdown } from './chunk-UY6SQVR2.js';
+import './chunk-WAZDP2WS.js';
+import './chunk-RYZPBJLB.js';
+export { explain } from './chunk-MD3CJ5YJ.js';
+import './chunk-MLH5LIGF.js';
+import './chunk-DXTPLVAK.js';
+export { OPFMarkdownError } from './chunk-KPALXWX3.js';
+import './chunk-HPEZCAYC.js';
+export { diff, merge } from './chunk-TAV5S2JG.js';
+export { CATALOG_SCHEMA, DEFAULT_VALIDATION_THRESHOLDS, OPFPatchError, OPFPatchValidationError, OPFValidationError, applyPatch, assertValid, assertValidCatalogRecord, catalogDisplayKinds, catalogSchemaNames, findValidationRule, resolveSlideContext, validate, validateCatalogRecord, validationCategories, validationRules } from './chunk-CIWC7DRZ.js';
 export { CATALOG_GROUP_PATTERN, CATALOG_REFERENCE_PATTERN, CHART_TYPES, DEFAULT_VARIABLE_DATE_FORMAT, ENGINE_DEFAULT_CHART_TYPES, ENGINE_DEFAULT_COLOR_SCHEME, ENGINE_DEFAULT_FONT_SCHEME, ENGINE_DEFAULT_THEME, LANGUAGES, LOGO_SHAPES, OPFCatalogsOptionError, OPFUnresolvedReferenceError, OPFVariableError, SLIDE_SCOPED_BUILTINS, SOCIAL_PLATFORMS, VARIABLE_KINDS, catalogGroupSource, catalogKinds, catalogRecords, catalogReferenceSites, chartNumber, coerceVariableValue, datasetDiagnostics, formatDataNumber, formatVariableNumber, fromExcelNumberFormat, hasContentVariables, inlineChartData, inlineDatasets, inlineTableData, isDatasetRef, isTemplate, isXYChartType, listBuiltinVariables, listVariables, normalizeLanguageFamily, numberFormatError, parseReference, resolveChartData, resolveDesignRecords, resolveFontScheme, resolveReference, resolveSlideVariables, resolveTableData, resolveVariables, suggestChartNumberFix, tableCellDisplayValue, toExcelNumberFormat, unresolvedReference, unusedDatasets, variableDeclarations } from './chunk-XRMV2GMB.js';
 export { OPFFormatError, format } from './chunk-EQ6S5SEZ.js';
 export { audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone } from './chunk-F4HFDP6I.js';